Spring AI核心概念与架构#

1. 整体定位#

LangChain 之于 Python，Spring AI 之于 Java。它不是模型，而是统一抽象层：屏蔽各家 Provider 差异，用 Spring Boot Starter + 自动配置开箱即用，application.yml 配 key 和模型即可切换厂商。2.0 核心仓库聚焦 OpenAI、Anthropic、Google GenAI、Amazon Bedrock、Mistral AI、DeepSeek、Ollama 等，其中 OpenAI、Anthropic、Google 改为基于厂商官方 SDK 实现；通义千问（DashScope）由 [Spring AI Alibaba框架](/topics/ai-agent/Spring AI Alibaba框架) 提供 starter（支持列表以官方文档为准）。

版本线（以官方 release notes 为准）： 1.0.x、1.1.x 仍在出维护版（基于 Spring Boot 3.x）；2.0.x 是当前主线（2026-08 发布 2.0.1），1.x 升 2.0 有较多破坏性变更（Jackson 2→3、MCP 注解包名调整、配置项去掉 .options 段等），升级前要读迁移说明。

2. 核心抽象#

3. ChatClient + Advisor（最该懂的两点）#

ChatMemory chatMemory = MessageWindowChatMemory.builder().maxMessages(10).build();

String answer = chatClient.prompt()
    .user(question)
    .advisors(QuestionAnswerAdvisor.builder(vectorStore).build(),     // RAG：自动检索注入上下文
              MessageChatMemoryAdvisor.builder(chatMemory).build())   // 记忆：自动拼历史
    .call().content();

Advisor 是 Spring AI 的精髓——RAG、记忆、安全检查都做成可插拔的拦截器链，类似 Servlet Filter / Spring Interceptor，不用手写”检索→拼 Prompt→调模型”的样板。注意当前版本的 Advisor 用 builder 创建，老教程里的 new QuestionAnswerAdvisor(vectorStore) 构造器写法已不推荐；QuestionAnswerAdvisor 需要引入 spring-ai-vector-store-advisor，更灵活的模块化 RAG 用 spring-ai-rag 的 RetrievalAugmentationAdvisor。

4. Function Calling（工具调用）#

用 @Tool（配合 @ToolParam 描述参数）注解或 MethodToolCallback / FunctionToolCallback 注册工具，Spring AI 自动把方法签名转成 JSON Schema 交给 LLM，LLM 决定调用后框架负责回调执行并把结果回传；returnDirect = true 可让工具结果直接返回调用方、不再经过模型。

传业务上下文：租户、用户 ID 这类值不应让模型填，用 ToolContext：

class CustomerTools {
    @Tool(description = "Retrieve customer information")
    Customer getCustomerInfo(Long id, ToolContext toolContext) {
        return customerRepository.findById(id, (String) toolContext.getContext().get("tenantId"));
    }
}

String reply = chatClient.prompt("Tell me more about the customer with ID 42")
    .tools(new CustomerTools())
    .toolContext(Map.of("tenantId", "acme"))   // 不会发给模型
    .call().content();

2.0 把工具调用循环提到 Advisor 链里，成为可组合的一环；另有 ToolSearchToolCallingAdvisor 支持工具多时按需逐步暴露（以官方文档为准）。

5. 结构化输出与 RAG ETL#

• 结构化输出：.entity(MyDto.class) 用 BeanOutputConverter 把 LLM 文本映射成 Java 对象（底层即 Schema/格式约束 + 解析），2.0 另有 StructuredOutputValidationAdvisor 校验失败自动重试修正，见 结构化输出与约束解码
• RAG ETL：DocumentReader（PDF/Markdown）→ TextSplitter 分块 → EmbeddingModel 向量化 → VectorStore 入库；检索侧用 QuestionAnswerAdvisor 或 RetrievalAugmentationAdvisor 自动召回

6. MCP 与可观测性#

• MCP 原生支持：基于官方 MCP Java SDK，同时提供 Client 和 Server starter，工具可标准化暴露给外部；2.0 升级到 MCP Java SDK 2.0.0（对应 MCP 2025-11-25 规范），提供 @McpTool / @McpResource / @McpPrompt 注解声明 Server 端能力，Streamable HTTP 成为默认传输（替代已废弃的 SSE），并支持 OAuth 2.0 / API Key 安全配置，见 MCP协议原理
• 可观测性：基于 Micrometer 暴露 token 用量、调用延迟等 Metrics 与 Tracing，天然接入 Spring Boot Actuator 体系，可通过 OpenTelemetry 导出到 Langfuse 等外部追踪平台

Spring AI 是 Spring 官方的 Java 大模型应用框架，1.0 在 2025 年 GA，2.0 在 2026 年 6 月 GA、基线升到 Spring Boot 4，定位类似 Java 世界的 LangChain，但更贴 Spring 生态。它本质是个统一抽象层，屏蔽 OpenAI、Anthropic、Google、Ollama 这些厂商的差异，用 Spring Boot Starter 自动配置，改个 yml 就能切模型，通义千问则通过 Spring AI Alibaba 接入。核心抽象几块：底层是 ChatModel 和 EmbeddingModel，对外入口是 ChatClient，一个 Fluent API 链式构建请求，类比 RestClient。最有特色的是 Advisor，它把 RAG、对话记忆、日志这些横切关注点做成可插拔的拦截器链，比如挂一个 QuestionAnswerAdvisor 就自动完成检索并注入上下文，挂 MessageChatMemoryAdvisor 就自动拼历史，不用手写样板，2.0 连工具调用循环也放进了 Advisor 链。工具调用用 @Tool 注解，框架自动把方法签名转成 JSON Schema 给 LLM，租户、用户这类业务上下文用 ToolContext 传，不经过模型。结构化输出用 .entity 直接映射成 Java 对象。RAG 有完整的 ETL 链：DocumentReader 读文档、TextSplitter 分块、向量化入 VectorStore，检索用 Advisor 自动召回。还原生支持 MCP，能做 Server 也能做 Client，2.0 默认用 Streamable HTTP 传输，可观测性基于 Micrometer 接入 Actuator。选它而不选 LangChain 的核心原因就是 Java 技术栈和 Spring 生态的无缝融合。结合项目时可以讲：同一套工具怎么同时给内部 Agent 和 MCP 外部客户端用、业务上下文怎么隔离、用什么数据验证效果。

追问方向：

• Spring AI 和 LangChain 怎么选？ → 看技术栈：Java/Spring Boot 团队选 Spring AI（生态融合、类型安全、运维体系复用），Python 团队选 LangChain。功能上 LangChain 生态更大更前沿，Spring AI 更稳更工程化
• Advisor 具体解决什么问题？ → 把”检索→拼 Prompt→调模型→存记忆”这套样板抽成可组合的拦截器链，类似 Servlet Filter；RAG/记忆/安全护栏/工具调用循环都能做成 Advisor 插拔，不污染业务代码
• 工具方法怎么拿到租户、用户这类业务上下文？ → 用 ToolContext：调用时 .toolContext(Map) 传入，工具方法声明 ToolContext 参数读取，这部分数据不发给模型，防止模型编造或越权；早期有团队用 ThreadLocal 侧信道传，异步/多线程执行工具时容易丢上下文，官方方案更稳。注意 2.0 起 ToolContext 里不再带对话历史
• ChatClient 和 ChatModel 区别？ → ChatModel 是底层模型接口（裸调用），ChatClient 是上层 Fluent 封装，带 Advisor、默认 System Prompt、结构化输出转换等便利能力，业务一般用 ChatClient
• Spring AI 怎么做 RAG？ → ETL 侧：DocumentReader+TextSplitter+EmbeddingModel+VectorStore 灌库；查询侧：QuestionAnswerAdvisor（简单）或 RetrievalAugmentationAdvisor（模块化，可插查询改写、多路检索）自动检索并把上下文拼进 Prompt
• 1.x 升 2.0 要注意什么？ → Spring Boot 4 / Spring Framework 7 基线、Jackson 3、MCP 注解和传输模块改包名、配置项结构调整、部分 Provider 移出核心仓库；先按迁移说明改依赖和配置，再跑回归

易错点：

• ❌ “Spring AI = 某个大模型” → 它是抽象框架，本身不含模型，要配 Provider
• ❌ “工具方法签名固定，业务上下文只能走 ThreadLocal” → 官方提供 ToolContext，上下文不经过模型直达工具方法
• ❌ “切换模型要改代码” → 面向 ChatModel 接口编程时，换 Provider 只改依赖和配置
• ❌ 照老教程写 new QuestionAnswerAdvisor(...) / new MessageChatMemoryAdvisor(...) → 当前版本用 XxxAdvisor.builder(...).build()